[WIP] Docs network 2.4 Declarative intent #26954

gundalow · 2017-07-18T13:24:34Z

SUMMARY

New guide_networking section for detailing non-module features:

network_declarative_intent

ISSUE TYPE

Docs Pull Request

ansibot · 2017-07-18T13:38:07Z

The test ansible-test sanity --test rstcheck failed with the following error:

docs/docsite/rst/network_declarative_intent.rst:118:0: Title underline too short.

click here for bot help

newswangerd · 2017-07-18T13:27:14Z

docs/docsite/rst/network_aggregate_resources.rst

+Overview
+========
+
+Consider the case if you wanted to ensure a set of vlans are present on a switch. Although at a high level thia sounds like a simple request, there in a slight nuance:


thia -> this

newswangerd · 2017-07-18T13:28:41Z

docs/docsite/rst/network_aggregate_resources.rst

+Overview
+========
+
+Consider the case if you wanted to ensure a set of vlans are present on a switch. Although at a high level thia sounds like a simple request, there in a slight nuance:


thia -> this

newswangerd · 2017-07-18T13:42:23Z

docs/docsite/rst/network_aggregate_resources.rst

+
+Continuing our vlan example, the following task ensure that vlans ``1``, ``2`` and ``3`` are in the states specified in the task, in `addition` to any existing vlans.
+
+This task *will not* change any vlans already configured on the switch, apart from the ones specified in the task.


Do additive resources just ignore any existing identical items and mark them as "unchanged"?

I've added

Ansible will ensure that the vlans specified in the task exist with the name and state specified.
Is that clearer?

newswangerd · 2017-07-18T13:47:03Z

docs/docsite/rst/network_aggregate_resources.rst

+       vlan_id: “{{ item.vlan_id }}”
+       name: “{{ item.name }}”
+       state: “{{ item.state | default(‘active’) }}”
+     with_items:


is there a reason additive items are added using a for loop rather than with an "additive" keyword like aggregate resources?

That's a good question. Originally I wanted to show the different ways of doing things, though that may just confuse the matter.

I've added a FIXME in the docs.

newswangerd · 2017-07-18T13:48:09Z

docs/docsite/rst/network_aggregate_resources.rst

+
+This task is very similar to the `additive resource` example above, though with the following differences:
+
+* The ``purge:`` option (which defaults to `no`) ensure that **only** the specified entries are present. All other entries will be **deleted**.


newswangerd · 2017-07-18T13:51:46Z

docs/docsite/rst/network_declarative_intent.rst

+
+.. code-block:: yaml
+
+   - name: Enable port


which modules is being used here? This example seems sort of incomplete.

newswangerd · 2017-07-18T14:04:40Z

docs/docsite/rst/network_declarative_intent.rst

+INTERNAL NOTE: Only now that we've explained the problem and given an example should we go into details.
+
+
+Declarative intent modules are designed to provide playbook designers a set of network modules that perform declarative configuration tasks on network devices.  This includes the ability to declaratively describe a configuration set.  In addition, declarative intent modules will also provide a means for declaratively expressing the intended ephemeral state of configuration resources.


Add some context:

Previous network modules allowed users to update a device by listing out the steps that need to be taking in order to achieve a desired state. Declarative intent modules......

newswangerd · 2017-07-18T14:09:37Z

docs/docsite/rst/network_declarative_intent.rst

+
+.. code-block:: yaml
+
+   - name: configure interface


It seems like there should be a module in this task

ansibot · 2017-07-26T14:25:21Z

The test ansible-test sanity --test rstcheck failed with the following error:

docs/docsite/rst/network_declarative_intent.rst:118:0: Title underline too short.

click here for bot help

ansibot · 2017-07-26T20:35:58Z

The test ansible-test sanity --test rstcheck failed with the following error:

docs/docsite/rst/network_declarative_intent.rst:218:0: Title underline too short.

click here for bot help

dharmabumstead

Initial review comments. Please flesh out the rest of 'declarative_intent' and I will make an edit pass over that as well. Good stuff - thanks @gundalow!

dharmabumstead · 2017-08-03T00:14:49Z

docs/docsite/rst/guide_networking.rst

+Networking Guides
+*****************
+
+This section explores particular Ansible Networking functionality and use cases in greater depth and provide a more "top down" explanation of some basic features.


"provide"->"provides". Also, I'd consider changing "top down explanation" to "an overview of some basic features". We're trying to minimize colloquialisms in the docs that might make future localization work more difficult.

dharmabumstead · 2017-08-03T00:16:43Z

docs/docsite/rst/network_aggregate_resources.rst

+
+.. contents:: Topics
+
+This section explores how and when `Aggregate Resources` can be used within Ansible Networking.


Please don't capitalize "Aggregate Resources" unless it's a proper name or a trademark. Re: 'Ansible Networking' - in most cases (unless it's a trademark or proper name) 'networking' shouldn't be capitalized.

dharmabumstead · 2017-08-03T00:16:56Z

docs/docsite/rst/network_aggregate_resources.rst

+
+This section explores how and when `Aggregate Resources` can be used within Ansible Networking.
+
+This document is part of a collection on Networking. The complete list of guides can be found at :ref:`Network Guides <guide_networking>`.


'networking'

dharmabumstead · 2017-08-03T00:18:23Z

docs/docsite/rst/network_aggregate_resources.rst

+
+Consider the case if you wanted to ensure a set of vlans are present on a switch. Although at a high level this sounds like a simple request, there in a slight nuance:
+
+* Should these vlans be in *addition* to the existing configuration?  - *additive*


Please spell these out. Something like: "If the vlans are to be in addition to the existing configuration, they are considered additive vlans".

dharmabumstead · 2017-08-03T00:19:00Z

docs/docsite/rst/network_aggregate_resources.rst

+
+.. versionadded:: 2.4
+
+   The ``aggregate:`` option has been added in Ansible 2.4 and is available in certain modules, see the modules documentation to see if the feature is available.


Semicolon or period and new sentence after "certain modules" please.

dharmabumstead · 2017-08-03T00:21:38Z

docs/docsite/rst/network_aggregate_resources.rst

+
+.. warning:: Why does ``purge`` default to ``no``?
+
+   To prevent from accidental deletion ``purge`` is always set to ``no``. This requires playbook writers to add ``purge: yes`` to enable this.


comma after deletion.

dharmabumstead · 2017-08-03T00:22:22Z

docs/docsite/rst/network_aggregate_resources.rst

+=======================================
+
+* What
+* Why: Cleaner short hand. Allows you to separate out what's common from what's item specific.


Please write this section out with full sentences. It reads like shorthand notes.

dharmabumstead · 2017-08-03T00:22:33Z

docs/docsite/rst/network_aggregate_resources.rst

+       state: active # override
+       purge: yes # override
+
+Become realy power on ``net_interfaces``, mtu, admin_state, description


dharmabumstead · 2017-08-03T00:22:50Z

docs/docsite/rst/network_aggregate_resources.rst

+       purge: yes
+
+
+When would you use aggregate resources with ``purge: true``?


dharmabumstead · 2017-08-03T00:23:11Z

docs/docsite/rst/network_declarative_intent.rst

+
+.. contents:: Topics
+
+This section explores what `Declarative Intent modules` are within the context of Ansible Networking.


Please revisit the capitalization here, as per comments above.

ganeshrn · 2017-08-29T13:32:34Z

docs/docsite/rst/network_aggregate_resources.rst

+   - name: configure vlans neighbor (delete others)
+     net_vlan:
+       aggregate:
+         - 1


This way of specifying value is not supported. Field under aggregate should be a key value pair.
eg: vlan_id: 1

ganeshrn · 2017-08-29T13:36:33Z

docs/docsite/rst/network_aggregate_resources.rst

+
+* Should we warn if purge & not aggregate
+
+  * Do we want to add ``required_if = [('purge', 'true', ['aggregate'])]``


This may not be always required. If aggregate is absent and purge is True it should delete all configured field under specified hierarchy.

ganeshrn · 2017-08-29T13:39:17Z

docs/docsite/rst/network_declarative_intent.rst

+       enabled: yes
+
+       # Intended state
+       state: connected


same as above

ganeshrn · 2017-08-29T14:01:04Z

docs/docsite/rst/network_declarative_intent.rst

+----------------------
+
+All declaritive intent modules support a ``delay:`` option. This represents the amount of time, in seconds, that Ansible will wait after setting declaritive configuration before checking the indended state. This pause is needed to allow the network device being configured to stablise, such as to allow handshake after bring up an interface.
+


Default value of delay is 10 seconds

Added "The default value is specified in the module's documentation."
Module documentation updated in #30344

dathelen · 2017-09-06T23:07:51Z

docs/docsite/rst/network_aggregate_resources.rst

+         - { vlan_id: 6 }
+       name: reserved_vlan # override
+       state: active # override
+


What happens if you use aggregate and the normal attribute?

- name: Reserve mgmt vlans net_vlan: aggregate: - { vlan_id: 4 } - { vlan_id: 5, name: mgmt } - { vlan_id: 6 } name: reserved_vlan # override state: active # override vlan_id: 5 <--- used in both aggregate and normal attribute name: not-mgmt

If this is not allowed might be good just to note that. Agreed this is not a useful thing to do but someone could do it and it would good to know what the outcome would be

ansibot · 2017-09-06T23:12:54Z

cc @dharmabumstead
click here for bot help

gundalow · 2017-09-12T16:39:01Z

Based on feedback in Network Contributors Summit in SF I've removed "aggregate" so in 2.4 we can release it as an "undocumented tech preview", this will allow further discussion to be had in the Community regarding how we want to proceed.

A backup of the original file can be found at https://gist.github.com/gundalow/c2a4fb51a093a72bc4a380535aa1d835

gundalow · 2017-09-15T15:55:24Z

The Core Network team has agreed that we will not add the technical guide for Declarative Intent into 2.4.0 to avoid confusing the end users.

Therefore removing 2.4.0 milestone

victorock · 2017-12-11T17:23:42Z

Rollback should be used carefully hence all changes should be validated as part of Network CI pipelines for Dev/Test/QA before being promoted to production.

ansibot · 2018-07-31T16:42:27Z

cc @acozine
click here for bot help

samccann · 2018-09-12T17:45:24Z

@gundalow @ganeshrn Anything we can do to move this one along?

gundalow added 9 commits July 7, 2017 15:58

network_aggregate_resources

0549656

more

58c3ec9

more

810b49d

contents:: Topics

4ffc156

more

d7b03e5

more

2e3f2cf

more

e8baaa0

more

b6d4317

more

cf551cb

newswangerd reviewed Jul 18, 2017

View reviewed changes

samdoran added networking Network category and removed needs_triage Needs a first human triage before being processed. labels Jul 19, 2017

gundalow added 2 commits July 25, 2017 18:43

typos

ffdec3d

more

70afaa5

ansibot removed the ci_verified Changes made in this PR are causing tests to fail. label Jul 26, 2017

ansibot added the ci_verified Changes made in this PR are causing tests to fail. label Jul 26, 2017

more

2201220

ansibot removed the ci_verified Changes made in this PR are causing tests to fail. label Jul 26, 2017

calfonso assigned gundalow Aug 1, 2017

dharmabumstead suggested changes Aug 3, 2017

View reviewed changes

Address Scott's feedback

083b798

ansibot added the stale_ci This PR has been tested by CI more than one week ago. Close and re-open this PR to get it retested. label Aug 29, 2017

ganeshrn suggested changes Aug 29, 2017

View reviewed changes

Qalthos modified the milestone: 2.4.0 Sep 1, 2017

dathelen reviewed Sep 6, 2017

View reviewed changes

gundalow changed the title ~~[WIP] Docs network 2.4~~ [WIP] Docs network 2.4 (aggregate & declarative intent) Sep 11, 2017

gundalow added 2 commits September 12, 2017 17:35

Correct example

c211776

Delete network_aggregate_resources.rst

6ef78fd

gundalow changed the title ~~[WIP] Docs network 2.4 (aggregate & declarative intent)~~ [WIP] Docs network 2.4 Declarative intent Sep 12, 2017

ansibot removed the stale_ci This PR has been tested by CI more than one week ago. Close and re-open this PR to get it retested. label Sep 12, 2017

dagwieers mentioned this pull request Sep 15, 2017

Hold off and redesign Declarative Intent ansible/proposals#70

Closed

gundalow modified the milestones: 2.4.0, 2.5.0 Sep 15, 2017

ansibot added stale_ci This PR has been tested by CI more than one week ago. Close and re-open this PR to get it retested. stale_review Updates were made after the last review and the last review is more than 7 days old. labels Sep 23, 2017

gundalow removed this from the 2.5.0 milestone Jan 17, 2018

ansibot added needs_rebase https://docs.ansible.com/ansible/devel/dev_guide/developing_rebasing.html and removed stale_review Updates were made after the last review and the last review is more than 7 days old. labels Feb 6, 2018

ansibot added docs This issue/PR relates to or includes documentation. and removed docs_pull_request labels Mar 1, 2018

acozine added this to Docsite work in Ansible-maintained Collections Documentation Mar 29, 2018

gundalow closed this Sep 12, 2018

Ansible-maintained Collections Documentation automation moved this from Docsite work to Done Sep 12, 2018

ansible locked and limited conversation to collaborators Jul 22, 2019


		Continuing our vlan example, the following task ensure that vlans ``1``, ``2`` and ``3`` are in the states specified in the task, in `addition` to any existing vlans.

		This task will not change any vlans already configured on the switch, apart from the ones specified in the task.


		This task is very similar to the `additive resource` example above, though with the following differences:

		* The ``purge:`` option (which defaults to `no`) ensure that only the specified entries are present. All other entries will be deleted.

		INTERNAL NOTE: Only now that we've explained the problem and given an example should we go into details.


		Declarative intent modules are designed to provide playbook designers a set of network modules that perform declarative configuration tasks on network devices. This includes the ability to declaratively describe a configuration set. In addition, declarative intent modules will also provide a means for declaratively expressing the intended ephemeral state of configuration resources.


		.. contents:: Topics

		This section explores how and when `Aggregate Resources` can be used within Ansible Networking.


		This section explores how and when `Aggregate Resources` can be used within Ansible Networking.

		This document is part of a collection on Networking. The complete list of guides can be found at :ref:`Network Guides <guide_networking>`.


		Consider the case if you wanted to ensure a set of vlans are present on a switch. Although at a high level this sounds like a simple request, there in a slight nuance:

		* Should these vlans be in addition to the existing configuration? - additive


		.. versionadded:: 2.4

		The ``aggregate:`` option has been added in Ansible 2.4 and is available in certain modules, see the modules documentation to see if the feature is available.


		.. warning:: Why does ``purge`` default to ``no``?

		To prevent from accidental deletion ``purge`` is always set to ``no``. This requires playbook writers to add ``purge: yes`` to enable this.

		purge: yes


		When would you use aggregate resources with ``purge: true``?


		.. contents:: Topics

		This section explores what `Declarative Intent modules` are within the context of Ansible Networking.


		* Should we warn if purge & not aggregate

		* Do we want to add ``required_if = [('purge', 'true', ['aggregate'])]``

		----------------------

		All declaritive intent modules support a ``delay:`` option. This represents the amount of time, in seconds, that Ansible will wait after setting declaritive configuration before checking the indended state. This pause is needed to allow the network device being configured to stablise, such as to allow handshake after bring up an interface.

[WIP] Docs network 2.4 Declarative intent #26954

[WIP] Docs network 2.4 Declarative intent #26954

Conversation

gundalow commented Jul 18, 2017 • edited

SUMMARY

ISSUE TYPE

ansibot commented Jul 18, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ansibot commented Jul 26, 2017

ansibot commented Jul 26, 2017

dharmabumstead left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ansibot commented Sep 6, 2017

gundalow commented Sep 12, 2017

gundalow commented Sep 15, 2017

victorock commented Dec 11, 2017

ansibot commented Jul 31, 2018

samccann commented Sep 12, 2018

gundalow commented Jul 18, 2017 •

edited